The Arsenal Files 8/The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO/prg_gen/euphor14.zip/LIBRARY.DOC

Text File | 1996-07-11 | 97KB | 2,572 lines

            Part II - Library Routines

 1. Introduction

 A large number of library routines are provided. Some are built right into
 the interpreter, ex.exe. Others are written in Euphoria and you must include
 one of the .e files in euphoria\include to use them. Where this is the case,
 the appropriate include file is noted in the "Syntax" part of the description.
 Of course an include file need only be included once in your program. The
 editor displays in magenta those routines that are built into the interpreter,
 ex.exe, and require no include file. You can override the definition of these
 built-in routines by defining your own routine with the same name. You will
 get a suppressible warning if you do this.

 To indicate what kind of object may be passed in and returned, the following
 prefixes are used:

   x - a general object (atom or sequence)
   s - a sequence
   a - an atom
   i - an integer
  fn - an integer used as a file number
  st - a string sequence, or single-character atom

 An error will result if an illegal argument value is passed to any of these
 routines.


 2. Routines by Application Area

 2.1  Predefined Types

      As well as declaring variables with these types, you can also call them
      just like ordinary functions, in order to test if a value is a certain
      type.

      integer     - test if an object is an integer
      atom        - test if an object is an atom
      sequence     - test if an object is a sequence

 2.2  Sequence Manipulation

      length     - return the length of a sequence
      repeat     - repeat an object n times to form a sequence of length n
      append     - add a new element to the end of a sequence
      prepend     - add a new element to the beginning of a sequence

 2.3  Searching and Sorting

      compare     - compare two objects
      find        - find an object in a sequence
      match       - find a sequence as a slice of another sequence
      sort        - sort the elements of a sequence into ascending order

 2.4  Pattern Matching

      lower     - convert a string to lower case
      upper     - convert a string to upper case
      wildcard_match - match a pattern containing ? and * wildcards
      wildcard_file  - match a file name against a wild card specification

 2.5  Math

      These routines can be applied to individual atoms or to sequences of
      values. See "Arithmetic Operations on Sequences" in chapter 2 of the
      reference manual.

      sqrt    - calculate the square root of an object
      rand    - generate random numbers
      sin    - calculate the sine of an angle
      cos    - calculate the cosine of an angle
      tan    - calculate the tangent of an angle
      log    - calculate the natural logarithm
      floor    - round down to the nearest integer
      remainder    - calculate the remainder when a number is divided by another
      power    - calculate a number raised to a power


 2.6  File and Device I/O

      To do input or output on a file or device you must first open the file
      or device, then use the routines below to read or write to it, then close
      the file or device. open() will give you a file number to use as the
      first argument of the other I/O routines. Certain files/devices are
      opened for you automatically (as text files):

         0 - standard input
         1 - standard output
         2 - standard error

      Unless you redirect them on the command line, standard input comes from
      the keyboard, standard output and standard error go to the screen. When
      you write something to the screen it is written immediately without
      buffering. If you write to a file, your characters are put into a buffer
      until there are enough of them to write out efficiently. When you close
      the file or device, any remaining characters are written out. Input from
      files is also buffered. When your program terminates, any files that are
      still open will be closed for you automatically.

      Note: If a program (written in Euphoria or any other language) has a
      file open for writing, and you are forced to reboot your computer for
      any reason, you should immediately run CHKDSK or SCANDISK to repair any
      damage to the file system that may have occurred.

      open    - open a file or device
      close    - close a file or device
      print    - print a Euphoria object with {,,} to show the structure
      ? x    - shorthand for print(1, x)
      printf    - formatted print to a file or device
      sprintf   - formatted print returned as a string sequence
      puts    - output a string sequence to a file or device
      getc    - read the next character from a file or device
      gets    - read the next line from a file or device
      get_key    - check for key pressed by the user, don't wait
      wait_key  - wait for user to press a key
      get    - read the representation of any Euphoria object from a file
      value    - read the representation of any Euphoria object from a string
      seek    - move to any character position within an open file
      where    - report the current character position in an open file
      current_dir - return the name of the current directory
      dir    - return complete info on all files in a directory

 2.7  Mouse Support

      get_mouse        - return mouse "events" (clicks, movements)
      mouse_events  - select mouse events to watch for
      mouse_pointer - display or hide the mouse pointer

 2.8  Operating System

      time    - number of seconds since a fixed point in the past
      date    - current year, month, day, hour, minute, second etc.
      command_line - DOS command-line used to run this program
      getenv    - get value of an environment variable
      system    - execute a DOS command line
      abort    - terminate execution

 2.9 Special Machine-dependent routines

      machine_func - specialized operations in ex.exe with return value
      machine_proc - specialized operations in ex.exe - no return value

 2.10 Debugging

      trace    - dynamically turns tracing on or off

 2.11 Graphics & Sound

      clear_screen - clear the screen - text or graphics
      position       - set cursor line and column
      get_position - return cursor line and column
      graphics_mode - select a new graphics (or text) mode
      video_config - return parameters of current graphics mode
      scroll       - scroll text screen up or down
      wrap       - control line wrap at right edge of screen
      cursor       - select cursor shape
      text_color   - set foreground text color
      bk_color       - set background color for text and graphics
      palette       - change color for one color number
      all_palette  - change color for all color numbers
      text_rows       - set number of lines on text screen
      pixel       - set color of a pixel or set of pixels
      get_pixel       - read color of a pixel or set of pixels
      draw_line    - connect a series of graphics points with a line
      polygon       - draw an n-sided figure
      ellipse       - draw an ellipse (circle)
      sound       - make a sound on the PC speaker
      read_bitmap  - read a bitmap file and return a sequence of pixels
      save_image   - save a rectangular region from a graphics screen
      save_text_image - save a rectangular region from a text screen
      display_image - display an image on the graphics screen
      display_text_image - display an image on the text screen
      get_active_page - return the page currently being written to
      set_active_page - change the page currently being written to
      get_display_page - return the page currently being displayed
      set_display_page - change the page currently being displayed

 2.12 Machine Level Interface

      With this low-level machine interface you can read and write to memory.
      You can also set up your own 386+ machine language routines and call
      them. The usual guarantee that Euphoria will protect you from machine-
      level errors does *not* apply when you use these routines. If you happen
      to reference a bad address, it will likely be caught by the Causeway DOS
      extender and you'll see an error message on the screen plus a dump of
      machine-level information in the file CW.ERR.

      Most Euphoria programmers will never use this interface, but it is
      important because it makes it possible to get into every nook and cranny
      of the hardware and operating system. For those with very specialized
      applications this could be crucial.

      Machine code routines can be written by hand, or taken from the
      disassembled output of a compiler for C or some other language.
      Remember that your machine code will be running in 32-bit protected
      mode. See demo\callmach.ex for an example.

      peek         - read one or more bytes from memory
      poke        - write one or more bytes to memory
      call        - call a machine language routine
      dos_interrupt - call a DOS software interrupt routine
      allocate        - allocate a block of memory
      free        - deallocate a block of memory
      allocate_low  - allocate a block of low memory (address less than 1Mb)
      free_low        - free a block allocated with allocate_low
      int_to_bytes  - convert an integer to 4 bytes
      bytes_to_int  - convert 4 bytes to an integer
      int_to_bits   - convert an integer to a sequence of bits
      bits_to_int   - convert a sequence of bits to an integer
      set_rand        - set the random number generator so it will generate
                    a repeatable series of random numbers
      use_vesa      - force the use of the VESA graphics standard
      crash_message - specify a message to be printed if Euphoria detects an
                    an error in your program


 3. Alphabetical Listing of all Routines



──────────────────────────────────────<?>───────────────────────────────────────

 Syntax:      ? x

 Description: This is just a shorthand way of saying:  print(1, x)
           i.e. printing the value of an expression to the standard output.

 Example:
          ? {1, 2} + {3, 4}

          would display {4, 6}.

 Comments:    ? differs slightly from print() since it will add new-lines to
           make the output more readable on your screen or wherever you
           have directed standard output.

 See Also:    print

────────────────────────────────────<abort>─────────────────────────────────────

 Syntax:      abort(a)

 Description: Abort execution of the program. The argument a is an integer
           status value to be returned to the operating system. A value of 0
           generally indicates successful completion of the program. Other
           values can indicate various kinds of errors. DOS batch (.bat)
           programs can read this value using the errorlevel feature.

 Comments:    abort() is useful when a program is many levels deep in
           subroutine calls, and execution must end immediately, perhaps
           due to a severe error that has been detected.

          Normally ex.exe returns an exit status code of 0. If your program
          fails with a Euphoria-detected compile-time or run-time error
          then a code of 1 is returned.

 Example:
           if x = 0 then
               puts(ERR, "can't divide by 0 !!!\n")
               abort(1)
           else
               z = y / x
           end if

 See Also:    crash_message

─────────────────────────────────<all_palette>──────────────────────────────────

 Syntax:      include graphics.e
          all_palette(s)

 Description: Specify new color intensities for the entire set of colors in the
           current graphics mode. s is a sequence of the form:

               {{r,g,b}, {r,g,b}, ... {r,g,b}}

           Each element specifies a new color intensity {red, green, blue}
           for the corresponding color number, starting with color number 0.
          The values for red, green and blue must be in the range 0 to 63.

 Comments:    This executes much faster than if you were to use palette() to
           set the new color intensities one by one. This procedure can
           be used with read_bitmap() to quickly display a picture on the
           screen.

 Example Program: demo\bitmap.ex

 See Also:    palette, read_bitmap, video_config, graphics_mode

───────────────────────────────────<allocate>───────────────────────────────────

 Syntax:      include machine.e
           a = allocate(i)

 Description: Allocate i contiguous bytes of memory. Return the address of the
          block of memory, or return 0 if the memory can't be allocated.

 Example:     buffer = allocate(100)
           for i = 0 to 99 do
                 poke(buffer+i, 0)
           end for

 See Also:    free, allocate_low, peek, poke, call

─────────────────────────────────<allocate_low>─────────────────────────────────

 Syntax:      include machine.e
           i2 = allocate_low(i1)

 Description: Allocate i1 contiguous bytes of low memory, i.e. conventional
            memory with an address below 1 megabyte. Return the address
           of the block of memory, or return 0 if the memory can't be
           allocated.

 Comment:     Some DOS software interrupts require that you pass one or
           more addresses in registers. These addresses must be
           conventional memory addresses for DOS to be able to read or
           write to them.

 Example Program: demo\dosint.ex

 See Also:    dos_interrupt, free_low, allocate, peek, poke

────────────────────────────────────<append>────────────────────────────────────

 Syntax:      s2 = append(s1, x)

 Description: Create a new sequence identical to s1 but with x added on the end
           as the last element. The length of s2 will be length(s1) + 1.

 Comments:    If x is an atom this is equivalent to s2 = s1 & x. If x is a
           sequence it is not equivalent.

          The extra storage is allocated automatically and very
          efficiently with Euphoria's dynamic storage allocation.
          The case where s1 and s2 are actually the same variable
          (as in Example 1 below) is highly optimized.

 Example 1:   You can use append to dynamically grow a sequence, e.g.

          sequence x

          x = {}
          for i = 1 to 10 do
          x = append(x, i)
          end for
          -- x is now {1,2,3,4,5,6,7,8,9,10}

 Example 2:   Any kind of Euphoria object can be appended to a sequence, e.g

           sequence x, y, z

           x = {"fred", "barney"}
           y = append(x, "wilma")
           -- y is now {"fred", "barney", "wilma"}

          z = append(append(y, "betty"), {"bam", "bam"})
          -- z is now {"fred", "barney", "wilma", "betty", {"bam", "bam"}}

 See Also:    prepend, concatenation (&) and sequence-formation {,,} operators
           in refman.doc

─────────────────────────────────────<atom>─────────────────────────────────────

 Syntax:      i = atom(x)

 Description: Return 1 if x is an atom else return 0.

 Comments:    This serves to define the atom type. You can also call it
          like an ordinary function to determine if an object is an
          atom.

 Example 1:
           atom a
           a = 5.99

 Example 2:
           line = gets(0)
           if atom(line) then
                puts(SCREEN, "end of file\n")
           end if

 See Also:    sequence

─────────────────────────────────<bits_to_int>──────────────────────────────────

 Syntax:      include machine.e
           a = bits_to_int(s)

 Description: Convert a sequence of binary 1's and 0's into a positive
            number. The least-significant bit is s[1].

 Comments:    If you print s the bits will appear in "reverse" order, but
           it is convenient to have increasing subscripts access bits of
           increasing significance.

 Example:     a = bits_to_int({1,1,1,0,1})
           -- a is 23 (binary 10111)

 See Also:    int_to_bits, and/or/not of sequences in refman.doc

───────────────────────────────────<bk_color>───────────────────────────────────

 Syntax:      include graphics.e
           bk_color(i)

 Description: Set the background color. In graphics modes the whole screen is
          affected immediately. In text modes any new characters that you
          print will have the new background color.

 Comments:    The various colors are defined as constants in graphics.e

           To restore the original background color when your program
           finishes, e.g. 0 - BLACK, you must call bk_color(0), and then if
           you are at the bottom line of the screen, ready to scroll up,
           you may have to actually print something before terminating your
           program. Printing '\n' may be enough.

 Example:     bk_color(BLACK)

 See Also:    text_color

─────────────────────────────────<bytes_to_int>─────────────────────────────────

 Syntax:      include machine.e
           a = bytes_to_int(s)

 Description: Convert a 4-element sequence of byte values to an atom.
            The elements of s are in the order expected for a 32-bit
            integer on the 386, i.e. least significant byte first.

 Comments:    The result could be greater than the integer type allows,
             so you should assign it to an atom.

            s would normally contain positive values that have been read
            using peek() from 4 consecutive memory locations.

 Example:     atom int32

           int32 = bytes_to_int({37,1,0,0})
           -- int32 is 37 + 256*1 = 293

 See Also:    int_to_bytes, bits_to_int, peek, poke

─────────────────────────────────────<call>─────────────────────────────────────

 Syntax:      call(a)

 Description: Call a machine language routine that starts at address a. This
          routine must execute a RET instruction #C3 to return control
          to Euphoria. The routine should save and restore any registers
          that it uses.

 Comments:    You can allocate a block of memory for the routine and then poke
            in the bytes of machine code. You might allocate other blocks of
            memory for data and parameters that the machine code can operate
            on. The addresses of these blocks could be poked into the
            machine code.

 Example Program: see demo\callmach.ex

 See Also:    allocate, free, peek, poke

─────────────────────────────────<clear_screen>─────────────────────────────────

 Syntax:      clear_screen()

 Description: Clear the screen using the current background color (may be set
           by bk_color()).

 Comments:    This works in all text and graphics modes.

 See Also:    bk_color, graphics_mode

────────────────────────────────────<close>─────────────────────────────────────

 Syntax:      close(fn)

 Description: Close a file or device and flush out any still-buffered
           characters.

 Comments:    Any still-open files will be closed automatically when your
           program terminates.

 See Also:    open

────────────────────────────────<command_line>──────────────────────────────────

 Syntax:      s = command_line()

 Description: Return a sequence of strings, where each string is a word from
           the command line that started your program. The first word will
           be the path to either the Euphoria executable, ex.exe or to
           your bound .exe file. The next word is either the name of your
           Euphoria .ex file, or the path to your bound .exe file. After
           that will come any extra words typed by the user. You can use
           these words in your program.

 Comments:    Euphoria (ex.exe) does not use any command line options. You
           are free to use any options for your own program.

           If you bind your program you will find that all command line
           arguments remain the same, except for the first two, even
           though your user no longer types "ex".

 Example 1:   -- The user types:  ex myprog myfile.dat 12345

           cmd = command_line()

           -- cmd will be:  {"C:\EUPHORIA\BIN\EX.EXE",
                       "myprog",
                       "myfile.dat",
                       "12345"}

 Example 2:   -- Your program is bound with the name "myprog.exe"
           -- and is stored in the directory c:\myfiles
           -- The user types:  myprog myfile.dat 12345

           cmd = command_line()

           -- cmd will be:  {"C:\MYFILES\MYPROG.EXE",
                       "C:\MYFILES\MYPROG.EXE", -- spacer
                       "myfile.dat",
                       "12345"}

          -- Note that all arguments remain the same as Example 1
          -- except for the first two. The second argument is always
          -- the same as the first and is inserted to keep the numbering
          -- of the subsequent arguments the same, whether your program
          -- is bound as a .exe or not.

 See Also:    getenv

───────────────────────────────────<compare>────────────────────────────────────

 Syntax:      i = compare(x1, x2)

 Description: Return 0 if objects x1 and x2 are identical, 1 if x1 is greater
          than x2, -1 if x1 is less than x2. Atoms are considered to be
          less than sequences. Sequences are compared "alphabetically"
          starting with the first element until a difference is found.

 Example 1:   x = compare({1,2,{3,{4}},5}, {2-1,1+1,{3,{4}},6-1})
           -- identical, x is 0

 Example 2:   if compare("ABC", "ABCD") < 0 then   -- -1
         -- will be true: ABC is "less" because it is shorter
           end if

 See Also:    equals (=) operator in refman.doc

─────────────────────────────────────<cos>──────────────────────────────────────

 Syntax:      x2 = cos(x1)

 Description: Return the cosine of x1, where x1 is in radians.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

 Example:     x = cos({.5, .6, .7})

           -- x is {0.8775826, 0.8253356, 0.7648422}

 See Also:    sin, tan, log, sqrt

────────────────────────────────<crash_message>─────────────────────────────────

 Syntax:      include machine.e
           crash_message(s)

 Description: Specify a string, s, to be printed on the screen in the event
           that Euphoria must stop your program due to a compile-time or
           run-time error.

 Comments:    Normally Euphoria prints a diagnostic message such as
           "syntax error" or "divide by zero" on the screen, as well as
           dumping debugging information into "ex.err". Euphoria's error
           messages will not be meaningful for your users unless they
           happen to be Euphoria programmers. By calling crash_message()
           you can control the message that will appear on the screen.
           Debugging information will still be stored in ex.err. You won't
           lose any information by doing this.

           s may contain '\n', new-line characters so your message can
           span several lines on the screen.

           You can call crash_message() as many times as you like from
           different parts of your program. The message specified by the
           last call will be the one displayed.

           Your crash message will always be displayed if a compile-time
           error (syntax, undeclared variable etc.) occurs. In the case of
           a run-time error (subscript out of bounds, uninitialized
           variable, divide by zero etc.) your program must be executed
           by the Complete Edition EX.EXE, or have been bound using
           the Complete Edition PDEX.EXE, or be under 300 statements.

 Example:     crash_message("An unexpected error has occurred!\n" &
                 "Please contact [e-mail]\n" &
                 "Do not delete the file \"ex.err\".\n")

 See Also:    abort
           Debugging section of refman.doc

─────────────────────────────────<current_dir>──────────────────────────────────

 Syntax:      include file.e
           s = current_dir()

 Description: Return the name of the current working directory.

 Example:
           sequence s
           s = current_dir()
           -- s would have "C:\EUPHORIA\DOC" if you were in that directory

 See Also:    dir, getenv

────────────────────────────────────<cursor>────────────────────────────────────

 Syntax:      include graphics.e
           cursor(i)

 Description: Select a style of cursor. graphics.e contains:

        global constant NO_CURSOR      = #2000,
             UNDERLINE_CURSOR       = #0607,
             THICK_UNDERLINE_CURSOR = #0507,
             HALF_BLOCK_CURSOR      = #0407,
             BLOCK_CURSOR           = #0007

           The second and fourth hex digits (from the left) determine the
           top and bottom rows of pixels in the cursor. The first digit
           controls whether the cursor will be visible or not. For example,
           #0407 turns on the 4th through 7th rows.

 Example:     cursor(BLOCK_CURSOR)

─────────────────────────────────────<date>─────────────────────────────────────

 Syntax:      s = date()

 Description: Return a sequence with the following information:
         { year (since 1900),
           month (January = 1),
           day (day of month, starting at 1),
           hour (0 to 23),
           minute (0 to 59),
           second (0 to 59),
           day of the week (Sunday = 1),
           day of the year (January 1st = 1) }

 Example:     now = date()
           -- now has: {95,3,24,23,47,38,6,83}
           -- i.e. Friday March 24, 1995 at 11:47:38pm, day 83 of the year

 See Also:    time

─────────────────────────────────────<dir>──────────────────────────────────────

 Syntax:      include file.e
           x = dir(st)

 Description: Return directory information for the file or directory named by
            st. If there is no file or directory with this name then -1 is
            returned.

           This information is similar to what you would get from the DOS
           DIR command. A sequence is returned where each element is a
           sequence that describes one file or subdirectory.

          If st names a directory you may have entries for "." and "..",
          just as with the DOS DIR command. If st names a file then x will
          have just one entry, i.e. length(x) will be 1.

          Each entry contains the name, attributes and file size as well
          as the year, month, day, hour, minute and second of the last
          modification. You can refer to the elements of an entry with
          the following constants defined in file.e:

        global constant
            D_NAME = 1,
            D_ATTRIBUTES = 2,
            D_SIZE = 3,

            D_YEAR = 4,
            D_MONTH = 5,
            D_DAY = 6,

            D_HOUR = 7,
            D_MINUTE = 8,
            D_SECOND = 9

          The attributes element is a string sequence containing
          characters chosen from:

            d - directory
            r - read only file
            h - hidden file
            s - system file
            v - volume-id entry
            a - archive file

          A normal file without special attributes would just have an empty
          string, "", in this field.

 Comments:    The top level directory, e.g. c:\ does not have "." or ".."
          entries.

          This function is often used just to test if a file or
          directory exists.

          Under Windows 95, st can have a long file or directory name
          anywhere in the path.

          The file name returned in D_NAME will be a standard DOS 8.3 name,
          even on Windows 95 or Windows NT. A new long-filename element
          may be added in a future release of Euphoria.

 Example:
          d = dir(current_dir())

          -- d might have:
        {
             {".",    "d",     0  1994, 1, 18,  9, 30, 02},
             {"..",   "d",     0  1994, 1, 18,  9, 20, 14},
             {"fred", "ra", 2350, 1994, 1, 22, 17, 22, 40},
             {"sub",  "d" ,    0, 1993, 9, 20,  8, 50, 12}
        }

          d[3][D_NAME] would be "fred"

 Example Programs: bin\search.ex, install.ex

 See Also: wildcard_file, current_dir, open

────────────────────────────────<display_image>─────────────────────────────────

 Syntax:      include image.e
           display_image(s1, s2)

 Description: Display at point s1 on the screen the 2-d sequence of pixels
           contained in s2. s1 is a two-element sequence {x, y}. s2 is a
           sequence of sequences, where each sequence is one horizontal
           line of pixel colors to be displayed. The first pixel of the
           first sequence is displayed at s1. It is the top-left pixel.
           All other pixels appear to the right or below of this point.

 Comments:    s2 might be the result of a previous call to save_image(), or
           read_bitmap(), or it could be something you have created.

          You could use save_image/display_image in a graphical user
          interface, to allow "pop-up" dialog boxes, and drop-down menus
          to appear and disappear without losing what was previously on
          the screen.

          The sequences (rows) of the image do not have to all be the
          same length.

 Example:     display_image({20,30}, {{1,5,9},
                       {2,4},
                       {1,0,1,0,4},
                       {5,5,5}})
           -- displays a small 4-line image at {20,30}, with the pixels
              appearing in the same relative positions as the layout
              above would indicate

 Example Program: see demo\bitmap.ex

 See Also:    save_image, read_bitmap, display_text_image

─────────────────────────────<display_text_image>───────────────────────────────

 Syntax:      include image.e
           display_text_image(s1, s2)

 Description: Display the 2-d sequence of characters and attributes contained
            in s2 at line s1[1], column s1[2]. s2 is a sequence of sequences,
            where each sequence is a string of characters and attributes to
            be displayed. The top-left character is displayed at s1. Other
            characters appear to the right or below of this position. The
            attributes indicate the foreground and background color of the
            preceding character.

 Comments:    s2 would normally be the result of a previous call to
           save_text_image(), although you could construct it yourself.

          This routine only works in text modes.

          You might use save_text_image/display_text_image in a text-mode
          graphical user interface, to allow "pop-up" dialog boxes, and
          drop-down menus to appear and disappear without losing what was
          previously on the screen.

           The sequences of the text image do not have to all be the same
           length.

 Example:     clear_screen()
           display_text_image({1,1}, {{'A', WHITE, 'B', GREEN},
                       {'C', RED+16*WHITE},
                       {'D', BLUE}})
           -- displays:  AB
                     C
                     D
             in the appropriate colors at the top left corner of the screen

 See Also:    save_text_image, display_image

────────────────────────────────<dos_interrupt>─────────────────────────────────
 Syntax:      include machine.e
           s2 = dos_interrupt(i, s1)

 Description: Call DOS software interrupt number i. s1 is a 10-element
          sequence of 16-bit register values to be used as input to the
          routine. s2 is a similar 10-element sequence containing
          output register values after the call returns. machine.e
          has the following declaration which shows the order of
          the register values in the input and output sequences.

        global constant REG_DI = 1,
                REG_SI = 2,
                REG_BP = 3,
                REG_BX = 4,
                REG_DX = 5,
                REG_CX = 6,
                REG_AX = 7,
                REG_FLAGS = 8,
                REG_ES = 9,
                REG_DS = 10

 Comments:    The register values returned in s2 are always positive values
           between 0 and #FFFF (65535).

           The flags value in s1[REG_FLAGS] is ignored on input. On output
          the least significant bit of s2[REG_FLAGS] has the carry flag,
          which usually indicates failure if it is set to 1.

          Certain interrupts require that you supply addresses of blocks of
          memory. These addresses must be conventional, low-memory
          addresses. You can allocate/deallocate low-memory using
          allocate_low() and free_low().

          With DOS software interrupts you can perform a wide variety
          of specialized operations, anything from formatting your
          floppy drive to rebooting your computer. For documentation
          on these interrupts consult a technical manual such as
          Peter Norton's "PC Programmer's Bible", or download Ralf
          Brown's Interrupt List from the WEB:

           http://www.cs.cmu.edu/afs/cs.cmu.edu/user/ralf/pub/WWW/files.html

 Example Program: demo\dosint.ex

 See Also:      allocate_low, free_low

──────────────────────────────────<draw_line>───────────────────────────────────

 Syntax:      include graphics.e
           draw_line(i, s)

 Description: Draw a line connecting two or more points in s, using color i.

 Example:     draw_line(WHITE, {{100, 100}, {200, 200}, {900, 700}})

          This would connect the three points in the sequence using a white
          line, i.e. a line would be drawn from {100, 100} to {200, 200}
          and another line would be drawn from {200, 200} to {900, 700}.

 See Also:    polygon, ellipse, pixel

───────────────────────────────────<ellipse>────────────────────────────────────

 Syntax:      include graphics.e
           ellipse(i1, i2, s1, s2)

 Description: Draw an ellipse with color i1. The ellipse will neatly fit inside
          the rectangle defined by diagonal points s1 {x1, y1} and s2
          {x2, y2}. If the rectangle is a square then the ellipse will be a
          circle. Fill the ellipse when i2 is 1. Don't fill when i2 is 0.

 Example:     ellipse(MAGENTA, 0, {10, 10}, {20, 20})

          This would make a magenta colored circle just fitting inside the
          square: {10, 10}, {10, 20}, {20, 20}, {20, 10}.

 Example Program: demo\sb.ex

 See Also:    polygon, draw_line

─────────────────────────────────────<find>─────────────────────────────────────

 Syntax:      i = find(x, s)

 Description: Find x as an element of s. If successful, return the index
           of the first element of s that matches. If unsuccessful
           return 0.

 Example 1:   location = find(11, {5, 8, 11, 2, 3})
          -- location is set to 3

 Example 2:   names = {"fred", "rob", "george", "mary", ""}
          location = find("mary", names)
          -- location is set to 4

 See Also:    match, compare

────────────────────────────────────<floor>─────────────────────────────────────

 Syntax:      x2 = floor(x1)

 Description: Return the greatest integer less than or equal to x1. (Round
           down to an integer.)

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

 Example:     y = floor({0.5, -1.6, 9.99, 100})
           -- y is {0, -2, 9, 100}

 See Also:    remainder

─────────────────────────────────────<free>─────────────────────────────────────

 Syntax:      include machine.e
           free(a)

 Description: Free up a previously allocated block of memory by specifying the
          address of the start of the block, i.e. the address that was
          returned by allocate().

 Comments:    Use free() to recycle blocks of memory during execution. This
            will reduce the chance of running out of memory or getting into
            excessive virtual memory swapping to disk. Do not reference
            a block of memory that has been freed. When your program
            terminates, all allocated memory will be returned to the system.

           Do not use free() to deallocate memory that was allocated using
           allocate_low(). Use free_low() for this purpose.

 Example Program: demo\callmach.ex

 See Also:    allocate, free_low

───────────────────────────────────<free_low>───────────────────────────────────

 Syntax:      include machine.e
           free_low(i)

 Description: Free up a previously allocated block of conventional memory by
           specifying the address of the start of the block, i.e. the
           address that was returned by allocate_low().

 Comments:    Use free_low() to recycle blocks of conventional memory during
           execution. This will reduce the chance of running out of
           conventional memory. Do not reference a block of memory that has
           been freed. When your program terminates, all allocated memory
           will be returned to the system.

           Do not use free_low() to deallocate memory that was allocated
           using allocate(). Use free() for this purpose.

 Example Program: demo\dosint.ex

 See Also:    allocate_low, dos_interrupt, free

─────────────────────────────────────<get>──────────────────────────────────────

 Syntax:      include get.e
           s = get(fn)

 Description: Read the next string of characters representing a Euphoria object
            from file fn, and convert it into the numeric value of that
            object. The result s will be a 2-element sequence:
            {error status, value}. Error status values are:

        GET_SUCCESS  -- object was read successfully
        GET_EOF      -- end of file before object was read
        GET_FAIL     -- object is not syntactically correct

          get() can read arbitrarily complicated Euphoria objects. You
          could have a long sequence of values in braces and separated by
          commas, e.g. {23, {49, 57}, 0.5, -1, 99, 'A', "john"}. A single
          call to get() will read in this entire sequence and return it's
          value as a result.

          Each call to get() picks up where the previous call left off. For
          instance, a series of 5 calls to get() would be needed to read
          in:

        99  5.2  {1,2,3}  "Hello"  -1

           On the sixth and any subsequent call to get() you would see a
           GET_EOF status. If you had something like:

             {1,2,xxx}

           in the input stream you would see a GET_FAIL error status
           because xxx is not a Euphoria object.

           Distinct "top-level" objects in the input stream must be
           separated from each other with one or more "whitespace"
           characters (blank, tab or \n). Whitespace is not necessary
           *within* a top-level object.

 Comments:    The combination of print() and get() can be used to save any
           Euphoria object to disk and later read it back. This technique
           could be used to implement a database as one or more large
           Euphoria sequences stored in disk files. The sequences could be
           read into memory, updated and then written back to disk after
           each series of transactions is complete.

           The value returned is not meaningful unless you have a
           GET_SUCCESS status.

 Example:     Suppose your program asks the user to enter a number from the
            keyboard. If he types 77.5, get(0) would return:

                 {GET_SUCCESS, 77.5}

            whereas gets(0) would return

              "77.5\n"

 Example Program: see demo\mydata.ex.

 See Also:    print, value, gets, getc

───────────────────────────────<get_active_page>────────────────────────────────

 Syntax:      include image.e
           i = get_active_page()

 Description: Some graphics modes on most video cards have multiple pages
           of memory. This lets you write screen output to one page
           while displaying a different page. get_active_page() returns
           the current page number that screen output is being sent to.

 Comments:    The active and display pages are both 0 by default.

          video_config() will tell you how many pages are available in
          the current graphics mode.

 See Also:    set_active_page, get_display_page, video_config

───────────────────────────────<get_display_page>───────────────────────────────

 Syntax:      include image.e
           i = get_display_page()

 Description: Some graphics modes on most video cards have multiple pages
           of memory. This lets you write screen output to one page
           while displaying another. get_display_page() returns the current
           page number that is being displayed on the monitor.

 Comments:    The active and display pages are both 0 by default.

          video_config() will tell you how many pages are available in
          the current graphics mode.

 See Also:    set_display_page, get_active_page, video_config

───────────────────────────────────<get_key>────────────────────────────────────

 Syntax:      i = get_key()

 Description: Return the key that was pressed by the user, without waiting for
          carriage return. Return -1 if no key was pressed. Special
          codes are returned for the function keys, arrow keys etc.

 Comments:    DOS can hold a small number of key-hits in its keyboard buffer.
           get_key() will return the next one from the buffer, or -1 if
           the buffer is empty.

           Run the key.bat program to see what key code is generated for
           each key on your keyboard.

 See Also:    wait_key, getc

──────────────────────────────────<get_mouse>───────────────────────────────────

 Syntax:      include mouse.e
           x = get_mouse()

 Description: Return the last mouse event in the form:

          {event, x, y}

            or return -1 if there has not been a mouse event since the last
            time get_mouse() was called.

          Constants have been defined in mouse.e for the possible mouse
          events:

            global constant MOVE = 1,
                    LEFT_DOWN = 2,
                    LEFT_UP = 4,
                    RIGHT_DOWN = 8,
                    RIGHT_UP = 16,
                    MIDDLE_DOWN = 32,
                    MIDDLE_UP = 64

          x and y are the coordinates of the mouse pointer at the time that
          the event occurred. get_mouse() returns immediately with either
          a -1 or a mouse event. It does not wait for an event to occur.
          You must check it frequently enough to avoid missing an event.
          When the next event occurs, the current event will be lost, if
          you haven't read it. In practice it is not hard to catch almost
          all events, and the ones that are lost are usually lost at a
          lower level in the system, beyond the control of your program.
          Losing a MOVE event is generally not too serious, as the next
          MOVE will tell you where the mouse pointer is.

 Comments:    You need a DOS mouse driver to use this routine.

           You can use get_mouse() in most text and graphics modes.

            The first call that you make to get_mouse() will turn on a
            mouse pointer, or a highlighted character.

          In text modes you will probably want to scale the x and y
          coordinates to get line and column positions.

          DOS generally does not support the use of a mouse in SVGA
          graphics modes (beyond 640x480 pixels). This restriction
          has been removed in Windows 95 (DOS 7.0).

          The x,y coordinate returned could be that of the very tip of the
          mouse pointer or might refer to the pixel pointed-to by
          the mouse pointer. Test this if you are trying to read the
          pixel color using get_pixel. You may have to read x-1,y-1
          instead.

 Example:     a return value of:

         {2, 100, 50}

           would indicate that the left button was pressed down while the
           mouse pointer was at position x=100, y=50 on the screen.

 See Also:    mouse_events, mouse_pointer

──────────────────────────────────<get_pixel>───────────────────────────────────

 Syntax:      include graphics.e
           x = get_pixel(s)

 Description: When s is a 2-element screen coordinate {x, y}, get_pixel()
           returns the color of the pixel on the screen at that point.

           When s is a 3-element sequence of the form: {x, y, n}
           get_pixel() returns a sequence of n color values for the
           points starting at {x,y} and moving to the right {x+1,y},
           {x+2,y} etc.

           Points off the screen have unpredictable color values.

 Comments:    When n is specified, a very fast algorithm is used to read the
           pixel colors on the screen. It is much faster to call get_pixel()
           once, specifying a large value of n, than it is to call it many
           times, reading one pixel color at a time.

 Example:     object x

           x = get_pixel({30,40})
           -- x is set to the color value of point x=30, y=40

           x = get_pixel({30,40,100})
           -- x is set to a sequence of 100 integer values, representing
           -- the colors starting at {30,40} and going to the right

 See Also:    pixel, graphics_mode, get_position

─────────────────────────────────<get_position>─────────────────────────────────

 Syntax:      include graphics.e
           s = get_position()

 Description: Return the current line and column position of the cursor as a
           2-element sequence {line, column}.

 See Also:    position, get_pixel

─────────────────────────────────────<getc>─────────────────────────────────────

 Syntax:      i = getc(fn)

 Description: Get the next character (byte) from file fn. -1 is returned at end
          of file.

 Comments:    File input using getc is buffered, i.e. getc does not actually
           go out to the disk for each character. Instead, a large block of
           characters will be read in at one time and returned to you one
           by one from a memory buffer.

 See Also:    gets, get_key, wait_key, open

────────────────────────────────────<getenv>────────────────────────────────────

 Syntax:      x = getenv(s)

 Description: Return the value of a DOS environment variable. If the variable
            is undefined return -1.

 Example:     e = getenv("EUDIR")
          -- e will be "C:\EUPHORIA" -- or perhaps D:, E: etc.

 Comments:    Because either a sequence or an atom (-1) might be returned, you
           should probably assign the result to a variable declared as
           object.

 See Also:    command_line

─────────────────────────────────────<gets>─────────────────────────────────────

 Syntax:      x = gets(fn)

 Description: Get the next sequence (one line, including '\n') of characters
           from file fn. The atom -1 is returned on end of file.

 Comments:    Because either a sequence or an atom (-1) might be returned, you
           should probably assign the result to a variable declared as
           object.

           The last line in a file might not end with a new-line '\n'
           character.

 Example:
          sequence buffer
          object line

          -- read a text file into a sequence
          buffer = {}
          while 1 do
               line = gets(0)
               if atom(line) then
              exit   -- end of file
               end if
               buffer = append(buffer, line)
          end while

 See Also:    getc, puts, open

────────────────────────────────<graphics_mode>─────────────────────────────────

 Syntax:      include graphics.e
           i1 = graphics_mode(i2)

 Description: Select graphics mode i2. See graphics.e for a list of valid
          graphics modes. If successful, i1 is set to 0, otherwise i1
          is set to 1.

 Comment:     Some modes are referred to as "text" modes because they only
           let you display text. Other modes are referred to as "graphics"
           modes because you can display pixels, lines, ellipses, etc. and
           usually text as well.

           As a convenience to your users, it is usually a good idea to
           switch back from a pixel graphics mode to the standard text
           mode before your program terminates. You can do this with
           graphics_mode(-1). If a graphics program leaves your screen
           in a mess, you can clear it up with the DOS CLS command, or
           by running ex or ed.

 Example:     if graphics_mode(18) then
               puts(SCREEN, "need VGA graphics!\n")
                 abort(1)
           end if
           draw_line(BLUE, {{0,0}, {50,50}})

 See Also:    text_rows, video_config

─────────────────────────────────<int_to_bits>──────────────────────────────────

 Syntax:      include machine.e
           s = int_to_bits(a, i)

 Description: Returns the low-order i bits of a, as a sequence of 1's and 0's.
           The least significant bits come first. For negative numbers
           the two's complement bit pattern is returned.

 Comments:    You can use subscripting, slicing, and/or/not of entire
           sequences etc. to manipulate sequences of bits. Shifting
           of bits and rotating of bits are easy to perform.

 Example:     s = int_to_bits(177, 8)
           -- s is {1,0,0,0,1,1,0,1} -- "reverse" order

 See Also:    bits_to_int, and/or/not of entire sequences in refman.doc

─────────────────────────────────<int_to_bytes>─────────────────────────────────

 Syntax:      include machine.e
           s = int_to_bytes(a)

 Description: Convert an integer into a sequence of 4 bytes. These bytes are in
          the order expected on the 386+, i.e. least significant byte
          first.

 Comments:    You might use this routine prior to poking the 4 bytes into
           memory for use by a machine language program.

          The integer can be negative. Negative byte-values will be
          returned, but after poking them into memory you will have
          the correct (two's complement) representation for the 386+.

 Example 1:   s = int_to_bytes(999)
           -- s is {231, 3, 0, 0}

 Example 2:   s = int_to_bytes(-999)
           -- s is {-231, -4, -1, -1}

 See Also:    bytes_to_int, int_to_bits, bits_to_int, peek, poke

───────────────────────────────────<integer>────────────────────────────────────

 Syntax:      i = integer(x)

 Description: Return 1 if x is an integer in the range -1073741824 to
           [phone]. Otherwise return 0.

 Comments:    This serves to define the integer type. You can also call it
           like an ordinary function to determine if an object is an
           integer.

 Example 1:   integer z
           z = -1

 Example 2:   if integer(y/x) then
               puts(SCREEN, "y is an exact multiple of x")
           end if

 See Also:    atom, sequence, floor

────────────────────────────────────<length>────────────────────────────────────

 Syntax:      i = length(s)

 Description: Return the length of s. s must be a sequence. An error will
           occur if s is an atom.

 Comments:    The length of each sequence is stored internally by the
           interpreter for quick access. (In other languages this
           operation requires a search through memory for an end marker.)

 Example 1:   length({{1,2}, {3,4}, {5,6}})   -- 3

 Example 2:   length("")    -- 0

 Example 3:   length({})    -- 0

─────────────────────────────────────<log>──────────────────────────────────────

 Syntax:      x2 = log(x1)

 Description: Return the natural logarithm of x1.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence. Note that log is only defined for positive
           numbers. Your program will abort with a message if you
           try to take the log of a negative number or zero.

 Example:     a = log(100)
           -- a is 4.60517

 See Also:    sin, cos, tan, sqrt

────────────────────────────────────<lower>─────────────────────────────────────

 Syntax:      include wildcard.e
           s2 = lower(s1)

 Description: Convert a string of characters to lower case.

 Example:     s = lower("Euphoria")
           -- s is "euphoria"

 See Also:    upper

─────────────────────────────────<machine_func>─────────────────────────────────

 Syntax:      x = machine_func(a, x)

 Description: see machine_proc() below

─────────────────────────────────<machine_proc>─────────────────────────────────

 Syntax:      machine_proc(a, x)

 Description: Perform a machine-specific operation such as graphics and sound
            effects. This routine should normally be called indirectly via
            one of the library routines in a Euphoria include file. A direct
            call can cause a machine exception if done incorrectly.

 See Also:    machine_func

────────────────────────────────────<match>─────────────────────────────────────

 Syntax:      i = match(s1, s2)

 Description: Try to match s1 against some slice of s2. If successful, return
          the element number of s2 where the (first) matching slice begins,
          else return 0.

 Example:     location = match("pho", "Euphoria")
          -- location is set to 3

 See Also:    find, compare, wildcard_match

─────────────────────────────────<mouse_events>─────────────────────────────────

 Syntax:      include mouse.e
           mouse_events(i)

 Description: Use this procedure to select the mouse events that you want
          get_mouse() to report. By default, get_mouse() will report all
          events. mouse_events() can be called at various stages of the
          execution of your program, as the need to detect events changes.

 Comments:    It is good practice to ignore events that you are not interested
              in, particularly the very frequent MOVE event, in order to reduce
              the chance that you will miss a significant event.

            The first call that you make to mouse_events() will turn on a
            mouse pointer, or a highlighted character.

 Example:     mouse_events(LEFT_DOWN + LEFT_UP + RIGHT_DOWN)
           -- will restrict get_mouse() to reporting the left button
             being pressed down or released, and the right button
             being pressed down. All other events will be ignored.

 See Also:    get_mouse, mouse_pointer

────────────────────────────────<mouse_pointer>─────────────────────────────────

 Syntax:      include mouse.e
           mouse_pointer(i)

 Description: If i is 0 hide the mouse pointer, otherwise turn on the mouse
           pointer. Multiple calls to hide the pointer will require
          multiple calls to turn it back on. The first call to either
          get_mouse() or mouse_events() above, will also turn the pointer
          on (once).

 Comments:    It may be necessary to hide the mouse pointer temporarily when
            you update the screen.

 See Also:    get_mouse, mouse_events

─────────────────────────────────────<open>─────────────────────────────────────

 Syntax:      fn = open(s1, s2)

 Description: Open a file or device, to get the file number. -1 is returned if
            the open fails. s1 is the path name of the file or device.  s2 is
            the mode in which the file is to be opened. Possible modes are:

          "r"  - open text file for reading
          "rb" - open binary file for reading
          "w"  - create text file for writing
          "wb" - create binary file for writing
          "u"  - open text file for update (reading and writing)
          "ub" - open binary file for update
          "a"  - open text file for appending
          "ab" - open binary file for appending

          Files opened for read or update must already exist. Files opened
          for write or append will be created if necessary. A file opened
          for write will be set to 0 bytes. Output to a file opened for
          append will start at the end of file.

          Output to text files will have carriage-return characters
          automatically added before linefeed characters. On input, these
          carriage-return characters are removed. A control-Z character
          (ASCII 26) will signal an immediate end of file.

          I/O to binary files is not modified in any way. Any byte values
          from 0 to 255 can be read or written.

          Some typical devices that you can open are:

          "CON"    the console (screen)
          "AUX"    the serial auxiliary port
          "COM1"   serial port 1
          "COM2"   serial port 2
          "PRN"    the printer on the parallel port
          "NUL"    a non-existent device that accepts and discards output

 Comment:     When running under Windows 95, you can open any existing file
           that has a long file or directory name in its path (i.e. greater
           than the standard DOS 8.3 format) using any open mode - read,
           write etc. However, if you try to create a *new* file (open with
           "w" or "a" and the file does not already exist) then the name
           will be truncated if necessary to an 8.3 style name. We hope to
           support creation of new long-filename files in a future release.

 Example:     integer file_num, file_num95
           sequence first_line
           constant ERROR = 2

           file_num = open("myfile", "r")
          if file_num = -1 then
                 puts(ERROR, "couldn't open myfile\n")
           else
               first_line = gets(file_num)
           end if

           -- on Windows 95:
           file_num95 = open("bigdirectoryname\\verylongfilename.abcdefg",
                       "r")
           if file_num95 != -1 then
           puts(1, "it worked!\n")
           end if

 See Also:    close

───────────────────────────────────<palette>────────────────────────────────────

 Syntax:      include graphics.e
           x = palette(i, s)

 Description: Change the color for color number i to s, where s is a sequence
           of color intensities: {red, green, blue}. Each value in s can be
           from 0 to 63. If successful, a 3-element sequence containing the
          previous color for i will be returned, and all pixels on the
          screen with value i will be set to the new color. If
          unsuccessful, the atom -1 will be returned.
 Example:
           x = palette(0, {15, 40, 10})
           -- color number 0 (normally black) is changed to a shade
              of mainly green.

 See Also:    all_palette

─────────────────────────────────────<peek>─────────────────────────────────────

 Syntax:      i = peek(a)
  or ...      s = peek({a, i})

 Description: Return a single byte value in the range 0 to 255 from machine
           address a, or return a sequence containing i consecutive byte
           values starting at address a in memory.

 Comments:    Since addresses are 32-bit numbers, they can be larger than
           the largest value of type integer (31-bits). Variables that
           hold an address should therefore be declared as atoms.

           It is faster to read several bytes at once using the second
           form of peek() than it is to read one byte at a time in a
           loop.

           Remember that peek takes just one argument, which in the
           second form is actually a 2-element sequence.

 Example:     The following are equivalent:
           -- method 1
           s = {peek(100), peek(101), peek(102), peek(103)}

           -- method 2
           s = peek({100, 4})

 See Also:    poke, allocate, free, allocate_low, free_low, call

────────────────────────────────────<pixel>─────────────────────────────────────

 Syntax:      include graphics.e
           pixel(x, s)

 Description: Set one or more pixels starting at point s, where s is a
           2-element screen coordinate {x, y}. If x is an atom, one pixel
           will be set to the color indicated by x. If x is a sequence then
           a number of pixels will be set, starting at s and moving to the
           right (increasing x value, same y value).

 Comments:    When x is a sequence, a very fast algorithm is used to put the
           pixels on the screen. It is much faster to call pixel() once,
           with a sequence of pixel colors, than it is to call it many
           times, plotting one pixel color at a time.

 Example 1:   pixel(BLUE, {50, 60})
          -- the point {50,60} is set to the color BLUE

 Example 2:   pixel({BLUE, GREEN, WHITE, RED}, {50,60})
           -- {50,60} set to BLUE
           -- {51,60} set to GREEN
           -- {52,60} set to WHITE
           -- {53,60} set to RED

 See Also:    get_pixel, graphics_mode

─────────────────────────────────────<poke>─────────────────────────────────────

 Syntax:      poke(a, i)
  or ..       poke(a, s)

 Description: First form - Write a single byte value, i, to memory address a.

           Second form - Write a sequence of byte values to consecutive
           memory locations starting at location a.

 Comments:    The lower 8-bits of each byte value, i.e. remainder(value, 256),
           is actually stored in memory.

           It is faster to write several bytes at once using the second
           form of poke() than it is to write one byte at a time in a
           loop.

           Writing to the screen memory with poke() can be much faster than
           using puts() or printf(), but the programming is more difficult.
           In most cases the speed is not needed. For example, the Euphoria
           editor never uses poke().

 Example Program: see demo\callmach.ex

 See Also:    peek, allocate, free, allocate_low, free_low, call

───────────────────────────────────<polygon>────────────────────────────────────

 Syntax:      include graphics.e
           polygon(i1, i2, s)

 Description: Draw a polygon with 3 or more vertices given in s, using a
           certain color i1. Fill the area if i2 is 1. Don't fill if i2
           is 0.

 Example:     polygon(GREEN, 1, {{100, 100}, {200, 200}, {900, 700}})
          -- makes a solid green triangle.

 See Also:    draw_line, ellipse

───────────────────────────────────<position>───────────────────────────────────

 Syntax:      position(a1, a2)

 Description: Set the cursor to line a1, column a2, where the top left corner
          of the screen is line 1, column 1. The next output to the screen
          will be printed at this location. position() will report an
          error if the location is off the screen.

 Comments:    The coordinate system for text is different from the one for
           graphics. In graphics modes the top-left is (x=0,y=0) and the
           first coordinate controls the horizontal, left<-->right location.

 Example:     position(2,1)
           -- the cursor moves to the beginning of the second line from
              the top

 See Also:    get_position, puts, print, printf

────────────────────────────────────<power>─────────────────────────────────────

 Syntax:      x3 = power(x1, x2)

 Description: Raise x1 to the power x2

 Comments:    The arguments to this functions may be atoms or sequences. The
           rules for arithmetic operations on sequences apply.

           Powers of 2 are calculated very efficiently.

 Example 1:   ? power(5, 2)
           -- 25 is printed

 Example 2:   ? power({5, 4, 3.5}, {2, 1, -0.5})
           -- {25, 4, 0.534522} is printed

 Example 3:   ? power(2, {1, 2, 3, 4})
           -- {2, 4, 8, 16}

 Example 4:   ? power({1, 2, 3, 4}, 2)
           -- {1, 4, 9, 16}

 See Also:    log, sqrt

───────────────────────────────────<prepend>────────────────────────────────────

 Syntax:      s2 = prepend(s1, x)

 Description: Prepend x to the start of sequence s1. The length of s2 will be
          length(s1) + 1.

 Comments:    If x is an atom this is the same as s2 = x & s1. If x is a
           sequence it is definitely not the same. e.g.

         prepend({1,2,3}, {0,0})
             -- {{0,0}, 1, 2, 3}

         {0,0} & {1,2,3}
                -- {0, 0, 1, 2, 3}

           The case where s1 and s2 are the same variable is handled
           very efficiently.

 Example:     s = {}
           for i = 1 to 10 do
           s = prepend(s, i)
            end for
            -- s is {10,9,8,7,6,5,4,3,2,1}

 See Also:    append, concatenation (&) and sequence-formation {,,} operators
           in refman.doc

────────────────────────────────────<print>─────────────────────────────────────

 Syntax:      print(fn, x)

 Description: Print, to file or device fn, an object x with braces { , , , }
           to show the structure.

 Comment:     If you want to see a string of characters, rather than just the
          ASCII codes, you need to use puts or printf.

 Example 1:   print(1, "ABC")  -- output is:  {65, 66, 67}
           puts(1, "ABC")   -- output is:  ABC

 Example 2:   print(1, repeat({10,20}, 3))
           -- output is: {{10,20},{10,20},{10,20}}

 See Also:    ?, puts, printf, get

────────────────────────────────────<printf>────────────────────────────────────

 Syntax:      printf(fn, st, x)

 Description: Print x, to file or device fn, using format string st. If x is
           an atom then a single value will be printed. If x is a sequence,
           then formats from st are applied to successive elements of x.
           Thus printf always takes exactly 3 arguments. Only the length of
           the last argument, containing the values to be printed, will
           vary. The basic formats are:

          %d - print an atom as a decimal integer
          %x - print an atom as a hexadecimal integer
          %o - print an atom as an octal integer
          %s - print a sequence as a string of characters
          %e - print an atom as a floating point number with exponential
                 notation
          %f - print an atom as a floating-point number with a decimal
               point but no exponent
          %g - print an atom as a floating point number using either
             the %f or %e format, whichever seems more appropriate
          %% - print the '%' character itself

          Field widths can be added to the basic formats, e.g. %5d, or
          %8.2f. The number before the decimal point is the minimum field
          width to be used. The number after the decimal point is the
          precision to be used.

          If the field width is negative, e.g. %-5d then the value will be
          left-justified within the field. Normally it will be right-
          justified. If the field width starts with a leading 0, e.g. %08d
          then leading zeros will be supplied to fill up the field. If the
          field width starts with a '+' e.g. %+7d then a plus sign will be
          printed for positive values.

 Example 1:   rate = 7.875
          printf(myfile, "The interest rate is: %8.2f\n", rate)

          The interest rate is:     7.88

 Example 2:   name="John Smith"
          score=97
          printf(1, "%15s, %5d\n", {name, score})

               John Smith,    97

 Comments:    Watch out for the following common mistake:

             printf(1, "%s", name)

          This will print only the first character of name, as each element
          of name is taken to be a separate value to be formatted. You must
          say this instead:

             printf(1, "%s", {name})

           Now, the third argument of printf is a one-element sequence
           containing a single value to be formatted.

 See Also:    sprintf, puts, open

─────────────────────────────────────<puts>─────────────────────────────────────

 Syntax:      puts(fn, x)

 Description: Output, to file or device fn, a single byte (atom) or sequence
           of bytes. The low order 8-bits of each value is actually sent
           out. If fn is the screen you will see text characters displayed.

 Comment:     When you output a sequence of bytes it must not have any
           (sub)sequences within it. It must be a sequence of atoms only.
           (Typically a string of ASCII codes).

 Example 1:   puts(SCREEN, "Enter your first name: ")

 Example 2:   puts(output, 'A')  -- the single byte 65 will be sent to output

 See Also:    printf, gets, open

─────────────────────────────────────<rand>─────────────────────────────────────

 Syntax:      x2 = rand(x1)

 Description: Return a random integer from 1 to x1, where x1 may be from 1 to
          the largest positive value of type integer (1073741823).

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

 Example:     s = rand({10, 20, 30})
           -- s might be: {5, 17, 23} or {9, 3, 12} etc.

 See Also:    set_rand

─────────────────────────────────<read_bitmap>──────────────────────────────────

 Syntax:      include image.e
           x = read_bitmap(st)

 Description: st is the name of a .bmp "bitmap" file. The file should be in
           the bitmap format. The most common variations of the format
           are supported. If the file is read successfully the result will
           be a 2-element sequence. The first element is the palette. The
           second element is a 2-d sequence of sequences containing a
           graphics-mode image. You can pass the palette to all_palette()
           (after dividing it by 4 to scale it). The image can be passed
           to display_image().

          Bitmaps of 2,4,16 or 256 colors are supported. If the file is
          not in a good format an error code (atom) is returned instead:

        global constant BMP_OPEN_FAILED = 1,
                BMP_UNEXPECTED_EOF = 2,
                BMP_UNSUPPORTED_FORMAT = 3

 Comments:    You can create your own bitmap picture files using Windows
           Paintbrush and many other graphics programs. You can then
           incorporate these pictures into your Euphoria programs.

 Example:     x = read_bitmap("c:\\windows\\arcade.bmp")
           -- note: double backslash needed to get single backslash in
                      a string

 Example Program: demo\bitmap.ex

 See Also:    palette, display_image

──────────────────────────────────<remainder>───────────────────────────────────

 Syntax:      x3 = remainder(x1, x2)

 Description: Compute the remainder after dividing x1 by x2. The result will
           have the same sign as x1, and the magnitude of the result will
           be less than the magnitude of x2.

 Comments:    The arguments to this function may be atoms or sequences. The
           rules for arithmetic operations on sequences apply.

 Example 1:   a = remainder(9, 4)
           -- a is 1

 Example 2:   s = remainder({81, -3.5, -9, 5.5}, {8, -1.7, 2, -4})
          -- s is {1, -0.1, -1, 1.5}

 Example 3:   s = remainder({17, 12, 34}, 16)
           -- s is {1, 12, 2}

 Example 4:   s = remainder(16, {2, 3, 5})
           -- s is {0, 1, 1}

────────────────────────────────────<repeat>────────────────────────────────────

 Syntax:      s = repeat(x, a)

 Description: Create a sequence of length a where each element is x.

 Comments:    When you repeat a sequence or a floating-point number the
           interpreter does not actually make multiple copies in memory.
           Rather, a single copy is "pointed to" a number of times.

 Example 1:   repeat(0, 10)      -- {0,0,0,0,0,0,0,0,0,0}

 Example 2:   repeat("JOHN", 4)  -- {"JOHN", "JOHN", "JOHN", "JOHN"}

 See Also:    append, prepend, sequence-formation operator in refman.doc

──────────────────────────────────<save_image>──────────────────────────────────

 Syntax:      include image.e
           s3 = save_image(s1, s2)

 Description: Save a rectangular image from a graphics screen. The result
           is a 2-d sequence of sequences containing all the pixels
           in the image. You can redisplay the image using display_image().
           s1 is a 2-element sequence {x1, y1} specifying the top-left
           pixel in the image. s2 is a sequence {x2, y2} specifying the
           bottom-right pixel.

 Comments:    You might use this in a graphical user interface to save a
           portion of the screen before you display a drop-down menu
           or dialog box.

 Example:     s = save_image({0,0}, {50,50})
           display_image({100,200}, s)
           display_image({300,400}, s)
           -- saves a 51x51 square image, then redisplays it at {100,200}
          -- and at {300,400}

 See Also:    display_image, save_text_image

───────────────────────────────<save_text_image>────────────────────────────────

 Syntax:      include image.e
           s3 = save_text_image(s1, s2)

 Description: Save a rectangular region of text from a text-mode screen.
           The result is a sequence of sequences containing ASCII characters
           and attributes from the screen. You can redisplay this text using
           display_text_image(). s1 is a 2-element sequence {line1, column1}
           specifying the top-left character. s2 is a sequence
           {line2, column2} specifying the bottom right character.

 Comments:    Because the character attributes are also saved, you will get
            the correct foreground and background color for each character
            if you redisplay the text.

          This routine only works in text modes.

           You might use this function in a text-mode graphical user
           interface to save a portion of the screen before displaying a
           drop-down menu, dialog box, alert box etc.

           If you are flipping video pages, note that this function reads
           from the current active page.

 Example:     If the top 2 lines of the screen have:
          Hello
          World

           s = save_text_image({1,1}, {2,5})

           Then s is something like:
                   {"H-e-l-l-o-",
                         "W-o-r-l-d-"}
           where we have indicated the attribute bytes by '-'

 See Also:    display_text_image, save_image, set_active_page

────────────────────────────────────<scroll>────────────────────────────────────

 Syntax:      include graphics.e
           scroll(i1, i2, i3)

 Description: Scroll a region of text on the screen either up (i1 positive) or
            down (i1 negative) by i1 lines. The region is the series of lines
          on the screen from i2 (top line) to i3 (bottom line), inclusive.
          A    new blank line will appear at the top or bottom.

 Example Program: see bin\ed.ex

 See Also:    clear_screen, text_rows

─────────────────────────────────────<seek>─────────────────────────────────────

 Syntax:      include file.e
           i1 = seek(fn, i2)

 Description: Seek (move) to any byte position in the file fn or to the end of
            file if i2 is -1. For each open file there is a current byte
            position that is updated as a result of I/O operations on the
            file. The initial file position is 0 for files opened for read,
            write or update. The initial position is the end of file for
            files opened for append. The value returned by seek() is 0 if the
            seek was successful, and non-zero if it was unsuccessful. It is
            possible to seek past the    end of a file. In this case undefined
            bytes will be added to the file to make it long enough for the
            seek.

 See Also:    where, open

───────────────────────────────────<sequence>───────────────────────────────────

 Syntax:      i = sequence(x)

 Description: Return 1 if x is a sequence else return 0.

 Comments:    This serves to define the sequence type. You can also call
           it like an ordinary function to determine if an object is
           a sequence.

 Example 1:
           sequence s
           s = {1,2,3}

 Example 2:
           if sequence(x) then
                 sum = 0
                 for i = 1 to length(x) do
                     sum = sum + x[i]
                 end for
           else
               -- x must be an atom
               sum = x
           end if

 See Also:    atom, object type in refman.doc

───────────────────────────────<set_active_page>────────────────────────────────

 Syntax:      include image.e
           set_active_page(i)

 Description: Select video page i to send all screen output to.

 Comments:    With multiple pages you can instantaneously change the entire
           screen without causing any visible "flicker". You can also
           save the screen and bring it back quickly.

          video_config() will tell you how many pages are available in
          the current graphics mode.

           By default, the active page and the display page are both 0.

           This works under DOS, or full-screen under Windows. In a
           partial-screen window you cannot change the active page.

 Example:     include image.e

           -- active & display pages are initially both 0
           puts(1, "\nThis is page 0\n")
           set_active_page(1)     -- screen output will now go to page 1
           clear_screen()
           puts(1, "\nNow we've flipped to page 1\n")
           if getc(0) then        -- wait for key-press
           end if
           set_display_page(1)    -- "Now we've ..." becomes visible
           if getc(0) then        -- wait for key-press
           end if
          set_display_page(0)    -- "This is ..." becomes visible again
          set_active_page(0)

 See Also:    get_active_page, set_display_page

──────────────────────────────<set_display_page>────────────────────────────────

 Syntax:      include image.e
           set_display_page(i)

 Description: Set video page i to be mapped to the visible screen.

 Comments:    With multiple pages you can instantaneously change the entire
           screen without causing any visible "flicker". You can also
           save the screen and bring it back quickly.

          video_config() will tell you how many pages are available in
          the current graphics mode.

           By default, the active page and the display page are both 0.

           This works under DOS, or full-screen under Windows. In a
           partial-screen window you cannot change the active page.

 Example:     See set_active_page example.

 See Also:    get_display_page, set_active_page

──────────────────────────────────<set_rand>────────────────────────────────────

 Syntax:      include machine.e
           set_rand(i)

 Description: Set the random number generator to a certain state, i, so that
           you will get a known series of random numbers on subsequent
           calls to rand().

 Comments:    Normally the numbers returned by the rand() function are totally
            unpredictable, and will be different each time you run your
            program. Sometimes however you may wish to repeat the same
            series of numbers, perhaps because you are trying to debug
            your program, or maybe you want the ability to generate the
            same output (e.g. a random picture) for your user upon request.

 Example:     sequence s, t
           s = repeat(0, 3)
           t = s

           set_rand(12345)
           s[1] = rand(10)
           s[2] = rand(100)
           s[3] = rand(1000)

           set_rand(12345)  -- same value for set_rand()
           t[1] = rand(10)  -- same arguments to rand() as before
           t[2] = rand(100)
           t[3] = rand(1000)
           -- at this point s and t will be identical

 See Also:    rand

─────────────────────────────────────<sin>──────────────────────────────────────

 Syntax:      x2 = sin(x1)

 Description: Return the sine of x1, where x1 is in radians.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

 Example:     sin_x = sin({.5, .9, .11})
           -- sin_x is {.479, .783, .110}

 See Also:    cos, tan

─────────────────────────────────────<sort>─────────────────────────────────────

 Syntax:      include sort.e
           s2 = sort(s1)

 Description: Sort s1 into ascending order using a fast sorting algorithm. The
            elements of s1 can be any mix of atoms or sequences. Atoms come
            before sequences, and sequences are sorted "alphabetically" where
            the first elements are more significant than the later elements.

 Comments:    By defining your own compare function to override the built-in
          compare(), you can change the ordering of values from sort(), and
          perhaps choose a field or element number on which to base the
          sort. Define your compare() as a global function before
          including sort.e.

 Example 1:   x = 0 & sort({7,5,3,8}) & 0
          -- x is set to {0, 3, 5, 7, 8, 0}

 Example 2:   y = sort({"Smith", "Jones", "Doe", 5.5, 4, 6})
           -- y is {4, 5.5, 6, "Doe", "Jones", "Smith"}

 Example 3:   database = sort({{"Smith",   95.0, 29},
                          {"Jones",   77.2, 31},
                          {"Clinton", 88.7, 44}})

          -- The 3 database "records" will be sorted by the first "field"
          -- i.e. by name. Where the first field (element) is equal it
          -- will be sorted by the second field etc.

          -- database is {{"Clinton", 88.7, 44},
                        {"Jones",   77.2, 31},
                        {"Smith",   95.0, 29}}

 See Also:    compare, match, find

────────────────────────────────────<sound>─────────────────────────────────────

 Syntax:      sound(i)

 Description: Turn on the PC speaker at frequency i. If i is 0 the speaker
           will be turned off.

 Example:     sound(1000) -- starts a fairly high pitched sound

───────────────────────────────────<sprintf>────────────────────────────────────

 Syntax:      s = sprintf(st, x)

 Description: This is exactly the same as printf(), except that the output
           is returned as a sequence of characters, rather than being
           sent to a file or device. st is a format string, x is the
           value or sequence of values to be formatted. printf(fn, st, x)
           is equivalent to puts(fn, sprintf(st, x)).

 Comments:    Some typical uses of sprintf are:

                1. Converting numbers to strings.
                2. Creating strings to pass to system().
                3. Creating formatted error messages and passing them to
                   a common error message handler.

 Example:     s = sprintf("%08d", 12345)
            -- s is "00012345"

 See Also:    printf, value, get

─────────────────────────────────────<sqrt>─────────────────────────────────────

 Syntax:      x2 = sqrt(x1)

 Description: Calculate the square root of x1.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

           Taking the square root of a negative number will abort your
           program with a run-time error message.

 Example:     r = sqrt(16)
           -- r is 4

 See Also:    log, power

────────────────────────────────────<system>────────────────────────────────────

 Syntax:      system(s, a)

 Description: Pass a command string s to the DOS command interpreter for
           execution. The argument a indicates the manner in which to
          return from the system call.

        value of a      return action
        ----------    -------------
             0      - restore previous graphics mode
                  (clears the screen)
             1      - make a beep sound, wait for a
                  key press, then restore the
                  graphics mode
             2      - do not restore graphics mode

 Comments:    Action 2 should only be used when it is known that the system
           call will not change the graphics mode.

          You can use Euphoria as a sophisticated DOS "batch" language
          by making calls to system().

           A Euphoria program will start off using extended memory. If
           extended memory runs out the program will consume conventional
           memory. If conventional memory runs out it will use virtual
           memory, i.e. swap space on disk. The DOS command run by system()
           will fail if there is not enough conventional memory available.
           To avoid this situation you can reserve some conventional (low)
           memory by typing:

                    SET CAUSEWAY=LOWMEM:xxx

           where xxx is the number of K of conventional memory to reserve.
           Type this before running your program. You can also put this in
           a .bat file that runs your program, or in AUTOEXEC.BAT. For
           example:

                    SET CAUSEWAY=LOWMEM:80
                    ex myprog.ex

           This will reserve 80K of conventional memory, which should be
           enough to run simple DOS commands like COPY, MOVE, MKDIR etc.

 Example:     system("copy temp.txt a:\\temp.bak", 2)
           -- note use of double backslash in literal string to get
              single backslash

 Example Program: see install.ex

 See Also:    dir, current_dir, getenv, command_line

─────────────────────────────────────<tan>──────────────────────────────────────

 Syntax:      x2 = tan(x1)

 Description: Return the tangent of x1, where x1 is in radians.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

 Example:     t = tan(1.0)
           -- t is 1.55741

 See Also:    sin, cos

──────────────────────────────────<text_color>──────────────────────────────────

 Syntax:      include graphics.e
           text_color(i)

 Description: Set the foreground text color. Add 16 to get blinking text
          in some modes. See graphics.e for a list of possible colors.

 Comments:    Text that you print *after* calling text_color will have the
           desired color.

           When your program terminates, the last color that you selected
           and actually printed on the screen will remain in effect.
           Thus you may have to print something, maybe just '\n', in
           WHITE to restore white text, especially if you are at the
           bottom line of the screen, ready to scroll up.

 Example:     text_color(BRIGHT_BLUE)

 See Also:    bk_color

──────────────────────────────────<text_rows>───────────────────────────────────

 Syntax:      include graphics.e
           i2 = text_rows(i1)

 Description: Set the number of lines of text on the screen to i1 if possible.
          i2 will be set to the actual new number of lines.

 Comments:    Values of 25, 28, 43 and 50 lines are supported by most graphics
           cards.

 See Also:    graphics_mode

─────────────────────────────────────<time>─────────────────────────────────────

 Syntax:      a = time()

 Description: Return the number of seconds since some fixed point in the past.
            The resolution on MS-DOS is about 0.05 seconds.

 Comments:    Take the difference between two readings of time(), to
           measure, for example, how long a section of code takes to
           execute.

 Example:     constant ITERATIONS = 1000000
           integer p
           atom t0, loop_overhead

           t0 = time()
           for i = 1 to ITERATIONS do
           end for
           loop_overhead = time() - t0

          t0 = time()
           for i = 1 to ITERATIONS do
                 p = power(2, 20)
           end for
           ? (time() - t0 - loop_overhead)/ITERATIONS
           -- calculates time (in seconds) for one call to power

 See Also:    date

────────────────────────────────────<trace>─────────────────────────────────────

 Syntax:      with trace
           trace(x)

 Description: If x is 1 or 2 then turn on full-screen statement tracing. If x
           is 0 then    turn off tracing. When x is 2 a monochrome trace
           display is forced on. Tracing only occurs in subroutines that
           were compiled when "with trace" was in effect. See the section
           on Debugging in refman.doc.

 Comments:    Use trace(2) if the color display is hard to view on your system.

 Example:     if x < 0 then
           -- ok, here's the case I want to debug...
           trace(1)
           -- etc.
          ...
          end if

 See Also:    Chapter 3 in refman.doc.

────────────────────────────────────<upper>─────────────────────────────────────

 Syntax:      include wildcard.e
           s2 = upper(s1)

 Description: Convert a string of characters to upper case.

 Example:     s = upper("Euphoria")
           -- s is "EUPHORIA"

 See Also:    lower

──────────────────────────────────<use_vesa>────────────────────────────────────

 Syntax:      include machine.e
           use_vesa(i)

 Description: use_vesa(1) will force Euphoria to use the VESA graphics
           standard. This may cause Euphoria programs to work better
           in SVGA graphics modes with certain graphics cards.
           use_vesa(0) will restore Euphoria's original method of
           using the graphics card.

 Comments:    Most people can ignore this. However if you experience
           difficulty in SVGA graphics modes you should try calling
           use_vesa(1) at the start of your program before any calls
           to graphics_mode().

           Arguments to use_vesa() other than 0 or 1 should not be used.

 Example:     use_vesa(1)
           fail = graphics_mode(261)

 See Also:    graphics_mode

────────────────────────────────────<value>─────────────────────────────────────

 Syntax:      include get.e
           s = value(st)

 Description: Read the string representation of a Euphoria object, and compute
           the value of that object. A 2-element sequence,
           {error_status, value} is actually returned, where error_status
           can be one of:

        GET_SUCCESS     -- a valid object representation was found
        GET_EOF        -- end of string reached too soon
        GET_FAIL    -- syntax is wrong

 Comments:    This works the same as get(), but it reads from a string
           that you supply, rather than from a file or device.

 Example 1:   s = value("12345"}
           -- s is {GET_SUCCESS, 12345}

 Example 2:   s = value("{0, 1, -99.9}")
           -- s is {GET_SUCCESS, {0, 1, -99.9}}

 Example 3:   s = value("+++")
           -- s is {GET_FAIL, 0}

 See Also:    get, sprintf, print

─────────────────────────────────<video_config>─────────────────────────────────

 Syntax:      include graphics.e
           s = video_config()

 Description: Return a sequence of values describing the current video
          configuration:
        {color monitor?, graphics mode, text rows, text columns,
         xpixels, ypixels, number of colors, number of pages}

           The following constants are defined in graphics.e:

            global constant VC_COLOR = 1,
                VC_MODE  = 2,
                VC_LINES = 3,
                VC_COLUMNS = 4,
                VC_XPIXELS = 5,
                VC_YPIXELS = 6,
                VC_NCOLORS = 7,
                VC_PAGES = 8

 Comments:    This routine makes it easy for you to parameterize a program
           so it will work in many different graphics modes.

           On the PC there are two types of graphics mode. The first type
           lets you print text only. The second type lets you plot pixels,
           or points, in various colors. The second type also usually lets
           you print text. You can tell that you are in a purely text mode,
           because the VC_XPIXELS and VC_YPIXELS fields will be 0.
           Library routines such as polygon, draw_line, and ellipse only
           work in a pixel mode.

 Example:     vc = video_config()  -- in mode 3 with 25-lines of text:
           -- vc is {1, 3, 25, 80, 0, 0, 32, 8}

 See Also:    graphics_mode

──────────────────────────────────<wait_key>────────────────────────────────────

 Syntax:      include get.e
           i = wait_key()

 Description: Return the next key pressed by the user. Don't return until
            a key is pressed.

 Comments:    You could achieve the same result using get_key() as follows:

                while 1 do
                    k = get_key()
                    if k != -1 then
                        exit
                    end if
                end while

           However, on multi-tasking systems like Windows, Windows NT,
           or OS/2 this "busy waiting" would slow the system down.
           wait_key() lets the operating system do other useful work
           while your program is waiting for the user to press a key.

           You could also use getc(0), assuming file number 0 was input
           from the keyboard, except that you wouldn't pick up the special
           codes for function keys, arrow keys etc.

 See Also:    get_key, getc

────────────────────────────────────<where>─────────────────────────────────────

 Syntax:      include file.e
           i = where(fn)

 Description: This function returns the current byte position in the file fn.
          This position is updated by reads, writes and seeks on the file.
          It is the place in the file where the next byte will be read
          from, or written to.

 See Also:    seek, open

────────────────────────────────<wildcard_file>─────────────────────────────────

 Syntax:      include wildcard.e
           i = wildcard_file(s1, s2)

 Description: Return 1 (TRUE) if the filename s2 matches the wild card pattern
           s1. Return 0 (FALSE) otherwise. This is similar to DOS wildcard
           matching, but better in some cases. * matches any 0 or more
           characters, ? matches any single character. Character comparisons
           are not case sensitive.

 Comments:    You might use this function to check the output of the dir()
           routine for file names that match a pattern supplied by the
           user of your program.

           In DOS "*ABC.*" will match ALL files. wildcard_file("*ABC.*", s)
           will only match when the file name part has "ABC" at the end
           (as you would expect).

 Example 1:   i = wildcard_file("AB*CD.?", "aB123cD.e")
          -- i is set to 1

 Example 2:   i = wildcard_file("AB*CD.?", "abcd.ex")
           -- i is set to 0, because the file type has 2 letters not 1

 Example Program: see bin\search.ex

 See Also:    wildcard_match, dir

────────────────────────────────<wildcard_match>────────────────────────────────

 Syntax:      include wildcard.e
           i = wildcard_match(s1, s2)

 Description: This function performs general matching of a string against a
           pattern containing * and ? wildcards. It returns 1 (TRUE) if
           string s2 matches pattern s1. It returns 0 (FALSE) otherwise.
           * matches any 0 or more characters. ? matches any
           single character. Character comparisons are case sensitive.

 Comments:    If you want case insensitive comparisons, pass both s1 and s2
           through upper(), or both through lower() before calling
           wildcard_match().

           If you want to detect a pattern anywhere within a string,
           add * to each end of the pattern:

             i = wildcard_match('*' & pattern & '*', string)

           There is currently no way to treat * or ? literally in a pattern.

 Example 1:   i = wildcard_match("A?B*", "AQBXXYY")
           -- i is 1 (TRUE)

 Example 2:   i = wildcard_match("*xyz*", "AAAbbbxyz")
           -- i is 1 (TRUE)

 Example 3:   i = wildcard_match("A*B*C", "a111b222c")
           -- i is 0 (FALSE) because upper/lower case doesn't match

 Example Program: see bin\search.ex

 See Also:    wildcard_file, match, upper, lower, compare

─────────────────────────────────────<wrap>─────────────────────────────────────

 Syntax:      include graphics.e
           wrap(i)

 Description: Allow text to wrap at the right margin (i = 1) or get truncated
            (i = 0).

 Comments:    By default text will wrap.

 Example:     puts(1, repeat('x', 100) & "\n\n")
           -- now have a line of 80 'x' followed a line of 20 more 'x'
           wrap(0)
           puts(1, repeat('x', 100) & "\n\n")
           -- creates just one line of 80 'x'

 See Also:    puts, position